Working With Data References15

All data handler components use data references to identify and locate a movie's container. Different types of containers may require different types of data references. For example, a reference to a memory-based movie may be a handle, while a reference to a file-based movie may be an alias.

Client programs can correlate data references with data handlers by matching the component's subtype value with the data reference type--the subtype value indicates the type of data reference the component supports. All data handlers with the same subtype value must support the same data reference type. To continue the previous example, Apple's memory-based data handler for the Macintosh uses handles (and has a subtype value of 'hndl' ), while the HFS data handler uses Alias Manager aliases (its subtype value is 'alis' ).

The DataHSetDataRef and DataHGetDataRef functions allow applications to assign your data handler's current data reference. The DataHCompareDataRef function asks your component to compare a data reference against the current data reference and indicate whether the references are equivalent (that is, refer to the same container). The DataHResolveDataRef permits your component to locate a data reference's container.

The DataHSetOSFileRef and DataHGetOSFileRef functions provide an alternative, system-specific mechanism for assigning your data handler's current data reference.

DataHSetDataRef

The DataHSetDataRef function assigns a data reference to your data handler component.



 
pascal ComponentResult DataHSetDataRef (

                     DataHandler dh,

                     Handle dataRef);

dh: Identifies the calling program's connection to your data handler component.
dataRef: Specifies the data reference. This parameter contains a handle to the information that identifies the container in question. Your component must make a copy of this handle.

DISCUSSION

Note that the type of data reference always corresponds to the type that your component supports, and that you specify in the component subtype value of your data handler. As a result, the client program does not provide a data reference type value (unlike the Movie Toolbox's data reference functions).

The client program is responsible for disposing of the handle. Consequently, your component must make a copy of the data reference handle.

RESULT CODES

Memory Manager errors

DataHGetDataRef

The DataHGetDataRef function retrieves your component's current data reference.



 
pascal ComponentResult DataHGetDataRef (

                     DataHandler dh,

                     Handle *dataRef);

dh: Identifies the calling program's connection to your data handler component.
dataRef: Contains a pointer to a data reference handle. Your component should make a copy of its current data reference in a handle and return that handle in this field. The client program is responsible for disposing of that handle.

RESULT CODES

Memory Manager errors

DataHCompareDataRef

Your component compares a supplied data reference against its current data reference and returns a Boolean value indicating whether the data references are equivalent (that is, the two data references identify the same container).



 
pascal ComponentResult DataHCompareDataRef (

                     DataHandler dh, 

                     Handle dataRef, 

                     Boolean *equal);

dh: Identifies the calling program's connection to your data handler component.
dataRef: Specifies the data reference to be compared to your component's current data reference.
equal: Contains a pointer to a Boolean. Your component should set that Boolean to true if the two data references identify the same container. Otherwise, set the Boolean to false .

DISCUSSION

Note that your component cannot simply compare the bits in the two data references. For example, two completely different aliases may refer to the same HFS file. Consequently, you need to completely resolve the data reference in order to determine the file identified by the reference.

DataHResolveDataRef

The DataHResolveDataRef function instructs your data handler component to locate the container associated with a given data reference.



 
pascal ComponentResult DataHResolveDataRef (

                     DataHandler dh, 

                     Handle theDataRef, 

                     Boolean *wasChanged, 

                     Boolean userInterfaceAllowed);

dh: Identifies the calling program's connection to your data handler component.
theDataRef: Specifies the data reference to be resolved.
wasChanged: Contains a pointer to a Boolean. Your component should set that Boolean to true if, in locating the container, your data handler updates any information in the data reference.
userInterfaceAllowed: Indicates whether your component may interact with the user when locating the container. If this parameter is set to true , your component may ask the user to help locate the container (for instance, by presenting a Find File dialog box).

DISCUSSION

This function is, essentially, equivalent to the Alias Manager's ResolveAlias function. The client program asks your component to locate the container that is associated with a given data reference. If your component determines that the data reference needs to be updated with more accurate location information, it should put the new information in the supplied data reference (and set the Boolean referred to by the wasChanged parameter to true ).

Client programs may call your data handler's DataHResolveDataRef function at any time. Typically, however, the Movie Toolbox uses this function as part of its strategy for opening and reading a movie container. As such, you can expect that the supplied data reference will identify a container that your component can support.

DataHSetOSFileRef

The DataHSetOSFileRef function assigns a movie container to your data handler component. Applications may use this function instead of calling the DataHSetDataRef function in cases where the applications have already opened the container.



 
pascal ComponentResult DataHSetOSFileRef (

                     DataHandler dh, 

                     long ref, 

                     long flags);

dh: Identifies the calling program's connection to your data handler component.
ref: Specifies the container. This parameter contains an operating system-specific file-access token. For example, on the Macintosh an application would supply the file reference it obtained by calling the FSOpenFile function. Under Windows, this parameter would contain an HFILE value obtained from the OpenFile function.
flags: Specifies access flags for the container. This parameter contains the access flags the application used when opening the container. Again, these are operating system-specific.

DISCUSSION

This function provides an alternative mechanism for assigning your data handler's current container. In some cases, an application may have created or opened a movie container prior to assigning the container to your handler. In such cases, the application may choose to provide its access token to your data handler, rather than using the DataHSetDataRef function to assign a data reference. The application must have opened the file before calling this function.

Note that your data handler must implement this function in a system-specific manner, and must verify that the access token is valid.

Applications must still call your handlers DataHOpenForRead or DataHOpenForWrite functions, as appropriate, before using your data handler to access the container.

RESULT CODES

`invalidDataRef`	-2012	Application already set a data reference
`memFullErr`	-108	Insufficient memory for operation

DataHGetOSFileRef

The DataHGetOSFileRef function retrieves your component's container access token, if it was assigned using the DataHSetOSFileRef function.



 
pascal ComponentResult DataHGetOSFileRef (

                     DataHandler dh, 

                     long *ref, 

                     long *flags);

dh: Identifies the calling program's connection to your data handler component.
ref: Contains a pointer to a long. Your component should return the container access token that the application provided when it called your DataHSetOSFileRef function.
flags: Contains a pointer to a long. Your component should return the access flags that the application provided when it called your DataHSetOSFileRef function.

RESULT CODES

`invalidDataRef`	-2012	Application already set a data reference
`memFullErr`	-108	Insufficient memory for operation